<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
       "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<title>
GnuDIP Release 2.3.5 - Linux/UNIX Client Script
</title>

<base target="_blank">

</head>

<body bgcolor=white>

<table><tr valign=middle><td>
<img align=middle src="gnudip.jpg" alt="GnuDIP Logo" border=0 height=60 width=113>
</td><td>
<h1>GnuDIP Release 2.3.5 - Linux/UNIX Client Script</h1>
</table>

<hr>

<p>
With this client you can have your IP address updated automatically at
several GnuDIP sites simultaneously. This client will only send an update
to the GnuDIP servers if the IP address at the time of the last update
is no longer valid, or enough time has expired. The validity of the old
address is determined without generating any network traffic.

<p>
The <code>gdipc.pl</code> script serves as the GnuDIP client. This and the
related <code>encpass.pl</code> script are in the
<a href="bin/"><code>bin</code></a> directory.

<p>
The client's features include:

<ul>
<li>
The client maintains the information for several GnuDIP domains in the same
configuration file. Using "<code>gdipc.pl -c</code>" will replace any existing entry.
To list the entries or
delete an entry the user must use a text editor. There is one line per GnuDIP domain. 

<p>
The script <code>encpass.pl</code> takes its plain text password argument
and prints the encrypted version. This script faciliates manual modification of the configuration
file.

<p>
<li>
The format of the lines in the configuration file is demonstrated by this
sample configuration file:

<pre>
tester;gnudip;localhost;f5d1278e8109edd94e1e4197e04873b9;/root/.GnuDIP2.cache.tester.gnudip;0;60
tester2;gnudip;localhost;179ad45c6ce2cb97cf1029e212046e81;/root/.GnuDIP2.cache.tester2.gnudip;0;2073600
</pre>

<p>
<li>
The client tries not to abuse a GnuDIP server, and maintains a cache file for each GnuDIP
domain towards this end. This is reflected in the user interface, of which this is a sample:

<pre>
# gdipc.pl -c
Using Update Configuration Mode
Configuration file name: /root/.GnuDIP2
Username: tester2
Domain: gnudip
Connect by direct TCP (d) or web server (w) [d]:
GnuDIP Server - host[:port]: localhost
Password: testpass
Cache File [/root/.GnuDIP2.cache.tester2.gnudip]:
Minimum Seconds Between Updates [0]:
Maximum Seconds Between Updates [2073600]:
</pre>

This is a sample update run:

<pre>
# gdipc.pl
====  gdipc.pl running:  Sun May 27 21:32:17 2001  ====
Configuration file name: /root/.GnuDIP2
Cache file name: /root/.GnuDIP2.cache.tester.gnudip
No update done for tester.gnudip - 127.0.0.1 still valid
Cache file name: /root/.GnuDIP2.cache.tester2.gnudip
Invalid login attempt for tester2.gnudip
</pre>

The IP address for <code>tester.gnudip</code> was not updated because the IP address
at the time of the last update is still valid, and because
"Maximum Seconds Between Updates" had not yet expired.

<p>
This is the contents of <code>/root/.GnuDIP2.cache.tester.gnudip</code>:

<pre>
127.0.0.1;990991068
</pre>

The status of a GnuDIP domain may be reset by deleting its cache file.

<p>
If "Minimum Seconds Between Updates" is specified, then an update will not be sent to
the server more often than this interval, even if the IP address at the time of the last
update is no longer valid.

<p>
<li>
The "help" printed by the script is as follows:

<pre>
# gdipc.pl -h
usage: gdipc.pl \
usage:   { -h | -v | -i [ -r] | [ -f configfile ] [ -c | -r | \
usage:       [ -o outfile | -a appendfile | -l logfile ] \
usage:       [ -g sendport:recvport ] [ -d repeatseconds] \
usage:       [ -w waitseconds] [ -q "addressquerycommand" ] ] \
usage:       [ -x "addresschangedcommand" ] }
usage: With no arguments, update server if address changed or time
usage: expired.
usage: -h: Print this usage message.
usage: -v: Show version information.
usage: -i: Prompt and read standard input rather than a configuration
usage:     file.
usage: -f: Specify a particular configuration file.
usage:     This will otherwise be .GnuDIP2 in the directory
usage:     specified by the HOME environment variable, or gdipc.conf
usage:     in the directory of the binary if HOME is not set.
usage: -c: Specify contents to write to configuration file.
usage: -r: Send an offline request to the server to remove your DNS hostname.
usage: -d: Run as a daemon. Perform client action immediately and then every
usage:     "repeatseconds" seconds.
usage: -o: Specify log file to overwrite on each run with output from script.
usage: -a: Specify log file to append on each run with all output from script.
usage: -l: Specify log file for daemon mode. Overwrite on first run, then
usage:     append.
usage: -w: Timeout in seconds when waiting for address validation packet.
usage:     Defaults to 1 second. Decimal point and fraction (e.g. "0.5") is
usage:     allowed.
usage: -g: Client is behind a gateway. Request GnuDIP server to register
usage:     address it sees connection from, and pass it back in response.
usage:     Specify port to send address validation packet to and port gateway
usage:     will forward it to.
usage: -q: Command to invoke to determine IP address to report to GnuDIP
usage:     server. Command must write address to standard output. When used
usage:     with -g, address is sent to server.
usage: -x: Command to invoke if address changed. This command can be used to
usage:     to take any actions required when the address changes. All
usage:     validated addresses are passed as arguments.
</pre>

<p><li>
You would want to run <code>gdipc.pl</code> at system startup and/or 
in exit scripts provided by daemons that dynamically configure interfaces.

<p>
Note that if one of these exit scripts runs very early during system startup,
BIND (or whatever name server you use) may not yet be running, so
<code>gdipc.pl</code> could not be run at that time.

<p>
Some examples of such daemons are:
<p>&nbsp;

<dl>

<dt>
<b><code>dhcpcd</code></b>:
<dd>
This is an excerpt from "<code>man dhcpcd</code>":

<pre>
       /etc/dhcpc/dhcpcd-&lt;interface&gt;.exe
              file which dhcpcd will try to execute  whenever  it
              detects a change in IP address.
</pre>

<p><dt>
<b><code>dhclient</code></b>:
<dd>
This is an excerpt from "<code>man dhclient-script</code>":

<pre>
       After  all  processing has completed, /etc/dhclient-script
       checks for the presence of  an  executable  /etc/dhclient-
       exit-hooks  script,  which if present is invoked using the
       '.' command.   The exit status is passed in the  exit_sta-
       tus  shell variable, and will always be zero if the script
       succeeded at the task for which it was invoked.
</pre>

<p><dt>
<b><code>pppd</code></b>:
<dd>
This is an excerpt from "<code>man pppd</code>":

<pre>
       /etc/ppp/ip-up
              A program or script which is executed when the link
              is  available  for sending and receiving IP packets
              (that is, IPCP has come up).  It is  executed  with
              the parameters

              interface-name  tty-device  speed  local-IP-address
              remote-IP-address ipparam
</pre>

</dl>

<p><li>
It would also be possible, if less desirable, to run it at regular intervals,
either using the <code>crontab</code> command to schedule it, or using the
<code>-d</code> option and starting it at system start up.

<p>
In order to capture the messages from <code>gdipc.pl</code> for the system log
you could do something like:

<pre>
/usr/local/gnudip/bin/gdipc.pl | /usr/bin/logger -t gdipc.pl
</pre>

from <code>dhclient-script</code> or:

<pre>
/usr/local/gnudip/bin/gdipc.pl -d 30 -l /var/log/gdipc.log
</pre>

when run at system start up.

<p><li>
If you have an internal network with a <b>Network Address Transalation/IP Masquerading
gateway</b> providing access to and from the public Internet, and you want to register
the external IP address of the NAT box with the GnuDIP server, you may want to run the
client on an internal machine. If the gateway is a closed proprietary device, you will
have to run the client on an internal machine. 

<p>
The client normally sends the address it detects at its end of the connection to
the server in the update request to the server, and the server registers this
address. It also remembers this address, and tests whether it is valid by sending
a UDP packet to a randomly selected port at this address. The client then waits
a short interval to receive this packet. If it is not received the IP address
is assumed to have changed, and an update is sent to the GnuDIP server.

<p>
To run behind an NAT box, the client needs to know the external address of the NAT box
and must be able to check whether that address has changed.

<p>
You must configure the NAT box to redirect some external UDP port to a UDP port on
the internal machine running the client. You provide these port numbers to the
client using the <code>-g</code> option. This option will
also cause the client to request the GnuDIP server to send the external
address of the NAT device (which the server sees as the other end of the client connection)
back in the reply to the update request. You must ensure that the GnuDIP servers you use
are at release 2.3.2 or later in order for this request to succeed.

</ul>

<p><hr>

</body>

</html>

